

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Module documentation &mdash; Python Video Stabilization with OpenCV</title>
  

  
  
    <link rel="shortcut icon" href="_static/vidstab_logo.ico"/>
  
  
  

  
  <script type="text/javascript" src="_static/js/modernizr.min.js"></script>
  
    
      <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
        <script type="text/javascript" src="_static/jquery.js"></script>
        <script type="text/javascript" src="_static/underscore.js"></script>
        <script type="text/javascript" src="_static/doctools.js"></script>
        <script type="text/javascript" src="_static/language_data.js"></script>
    
    <script type="text/javascript" src="_static/js/theme.js"></script>

    

  
  <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
  <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="prev" title="Basic usage" href="usage.html" /> 
</head>

<body class="wy-body-for-nav">

   
  <div class="wy-grid-for-nav">
    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >
          

          
            <a href="index.html">
          

          
            
            <img src="_static/vidstab_logo2.png" class="logo" alt="Logo"/>
          
          </a>

          
            
            
          

          
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

          
        </div>

        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
          
            
            
              
            
            
              <ul>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Install Options</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="usage.html">Basic usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="usage.html#advanced-usage">Advanced usage</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Module documentation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#module-vidstab"><code class="docutils literal notranslate"><span class="pre">VidStab</span></code> class</a></li>
<li class="toctree-l2"><a class="reference internal" href="#utility-functions">Utility functions</a></li>
</ul>
</li>
</ul>

            
          
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" aria-label="top navigation">
        
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">vidstab</a>
        
      </nav>


      <div class="wy-nav-content">
        
        <div class="rst-content">
        
          















<div role="navigation" aria-label="breadcrumbs navigation">

  <ul class="wy-breadcrumbs">
    
      <li><a href="index.html">Docs</a> &raquo;</li>
        
      <li>Module documentation</li>
    
    
      <li class="wy-breadcrumbs-aside">
        
            
            <a href="_sources/module_docs.rst.txt" rel="nofollow"> View page source</a>
          
        
      </li>
    
  </ul>

  
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="module-documentation">
<h1>Module documentation<a class="headerlink" href="#module-documentation" title="Permalink to this headline">¶</a></h1>
<div class="section" id="module-vidstab">
<span id="vidstab-class"></span><h2><code class="docutils literal notranslate"><span class="pre">VidStab</span></code> class<a class="headerlink" href="#module-vidstab" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="vidstab.VidStab">
<em class="property">class </em><code class="sig-prename descclassname">vidstab.</code><code class="sig-name descname">VidStab</code><span class="sig-paren">(</span><em class="sig-param">kp_method='GFTT'</em>, <em class="sig-param">processing_max_dim=inf</em>, <em class="sig-param">*args</em>, <em class="sig-param">**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.VidStab" title="Permalink to this definition">¶</a></dt>
<dd><p>A class for stabilizing video files</p>
<p>The VidStab class can be used to stabilize videos using functionality from OpenCV.
Input video is read from file, put through stabilization process, and written to
an output file.</p>
<p>The process calculates optical flow (<code class="docutils literal notranslate"><span class="pre">cv2.calcOpticalFlowPyrLK</span></code>) from frame to frame using
keypoints generated by the keypoint method specified by the user.  The optical flow will
be used to generate frame to frame transformations (<code class="docutils literal notranslate"><span class="pre">cv2.estimateRigidTransform</span></code>).
Transformations will be applied (<code class="docutils literal notranslate"><span class="pre">cv2.warpAffine</span></code>) to stabilize video.</p>
<p>This class is based on the <a class="reference external" href="http://nghiaho.com/?p=2093">work presented by Nghia Ho</a></p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>kp_method</strong> – String of the type of keypoint detector to use. Available options are:
<code class="docutils literal notranslate"><span class="pre">[&quot;GFTT&quot;,</span> <span class="pre">&quot;BRISK&quot;,</span> <span class="pre">&quot;DENSE&quot;,</span> <span class="pre">&quot;FAST&quot;,</span> <span class="pre">&quot;HARRIS&quot;,</span> <span class="pre">&quot;MSER&quot;,</span> <span class="pre">&quot;ORB&quot;,</span> <span class="pre">&quot;STAR&quot;]</span></code>.
<code class="docutils literal notranslate"><span class="pre">[&quot;SIFT&quot;,</span> <span class="pre">&quot;SURF&quot;]</span></code> are additional non-free options available depending
on your build of OpenCV.  The non-free detectors are not tested with this package.</p></li>
<li><p><strong>processing_max_dim</strong> – <p>Working with large frames can harm performance (especially in live video).
Setting this parameter can restrict frame size while processing.
The outputted frames will remain the original size.</p>
<p>For example:</p>
<ul>
<li><p>If an input frame shape is <cite>(200, 400, 3)</cite> and <cite>processing_max_dim</cite> is
100.  The frame will be resized to <cite>(50, 100, 3)</cite> before processing.</p></li>
<li><p>If an input frame shape is <cite>(400, 200, 3)</cite> and <cite>processing_max_dim</cite> is
100.  The frame will be resized to <cite>(100, 50, 3)</cite> before processing.</p></li>
<li><p>If an input frame shape is <cite>(50, 50, 3)</cite> and <cite>processing_max_dim</cite> is
100.  The frame be unchanged for processing.</p></li>
</ul>
</p></li>
<li><p><strong>args</strong> – Positional arguments for keypoint detector.</p></li>
<li><p><strong>kwargs</strong> – Keyword arguments for keypoint detector.</p></li>
</ul>
</dd>
<dt class="field-even">Variables</dt>
<dd class="field-even"><ul class="simple">
<li><p><strong>kp_method</strong> – a string naming the keypoint detector being used</p></li>
<li><p><strong>processing_max_dim</strong> – max image dimension while processing transforms</p></li>
<li><p><strong>kp_detector</strong> – the keypoint detector object being used</p></li>
<li><p><strong>trajectory</strong> – a 2d showing the trajectory of the input video</p></li>
<li><p><strong>smoothed_trajectory</strong> – a 2d numpy array showing the smoothed trajectory of the input video</p></li>
<li><p><strong>transforms</strong> – a 2d numpy array storing the transformations used from frame to frame</p></li>
</ul>
</dd>
</dl>
<dl class="method">
<dt id="vidstab.VidStab.apply_transforms">
<code class="sig-name descname">apply_transforms</code><span class="sig-paren">(</span><em class="sig-param">input_path</em>, <em class="sig-param">output_path</em>, <em class="sig-param">output_fourcc='MJPG'</em>, <em class="sig-param">border_type='black'</em>, <em class="sig-param">border_size=0</em>, <em class="sig-param">layer_func=None</em>, <em class="sig-param">show_progress=True</em>, <em class="sig-param">playback=False</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.VidStab.apply_transforms" title="Permalink to this definition">¶</a></dt>
<dd><p>Apply stored transforms to a video and save output to file</p>
<p>Use the transforms generated by <code class="docutils literal notranslate"><span class="pre">VidStab.gen_transforms</span></code> or <code class="docutils literal notranslate"><span class="pre">VidStab.stabilize</span></code> in stabilization process.
This method is a wrapper for <code class="docutils literal notranslate"><span class="pre">VidStab.stabilize</span></code> with <code class="docutils literal notranslate"><span class="pre">use_stored_transforms=True</span></code>;
it is included for backwards compatibility.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>input_path</strong> – Path to input video to stabilize.
Will be read with <code class="docutils literal notranslate"><span class="pre">cv2.VideoCapture</span></code>; see opencv documentation for more info.</p></li>
<li><p><strong>output_path</strong> – Path to save stabilized video.
Will be written with <code class="docutils literal notranslate"><span class="pre">cv2.VideoWriter</span></code>; see opencv documentation for more info.</p></li>
<li><p><strong>output_fourcc</strong> – FourCC is a 4-byte code used to specify the video codec.</p></li>
<li><p><strong>border_type</strong> – How to handle negative space created by stabilization translations/rotations.
Options: <code class="docutils literal notranslate"><span class="pre">['black',</span> <span class="pre">'reflect',</span> <span class="pre">'replicate']</span></code></p></li>
<li><p><strong>border_size</strong> – Size of border in output.
Positive values will pad video equally on all sides,
negative values will crop video equally on all sides,
<code class="docutils literal notranslate"><span class="pre">'auto'</span></code> will attempt to minimally pad to avoid cutting off portions of transformed frames</p></li>
<li><p><strong>layer_func</strong> – Function to layer frames in output.
The function should accept 2 parameters: foreground &amp; background.
The current frame of video will be passed as foreground,
the previous frame will be passed as the background
(after the first frame of output the background will be the output of
layer_func on the last iteration)</p></li>
<li><p><strong>show_progress</strong> – Should a progress bar be displayed to console?</p></li>
<li><p><strong>playback</strong> – Should the a comparison of input video/output video be played back during process?</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>Nothing is returned.  Output of stabilization is written to <code class="docutils literal notranslate"><span class="pre">output_path</span></code>.</p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab.VidStab</span> <span class="kn">import</span> <span class="n">VidStab</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">gen_transforms</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">apply_transforms</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">,</span> <span class="n">output_path</span><span class="o">=</span><span class="s1">&#39;stable_video.avi&#39;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="vidstab.VidStab.gen_transforms">
<code class="sig-name descname">gen_transforms</code><span class="sig-paren">(</span><em class="sig-param">input_path</em>, <em class="sig-param">smoothing_window=30</em>, <em class="sig-param">show_progress=True</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.VidStab.gen_transforms" title="Permalink to this definition">¶</a></dt>
<dd><p>Generate stabilizing transforms for a video</p>
<p>This method will populate the following instance attributes: trajectory, smoothed_trajectory, &amp; transforms.
The resulting transforms can subsequently be used for video stabilization by using <code class="docutils literal notranslate"><span class="pre">VidStab.apply_transforms</span></code>
or <code class="docutils literal notranslate"><span class="pre">VidStab.stabilize</span></code> with <code class="docutils literal notranslate"><span class="pre">use_stored_transforms=True</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>input_path</strong> – Path to input video to stabilize.
Will be read with <code class="docutils literal notranslate"><span class="pre">cv2.VideoCapture</span></code>; see opencv documentation for more info.</p></li>
<li><p><strong>smoothing_window</strong> – window size to use when smoothing trajectory</p></li>
<li><p><strong>show_progress</strong> – Should a progress bar be displayed to console?</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>Nothing; this method populates attributes of VidStab objects</p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab.VidStab</span> <span class="kn">import</span> <span class="n">VidStab</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">gen_transforms</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">apply_transforms</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">,</span> <span class="n">output_path</span><span class="o">=</span><span class="s1">&#39;stable_video.avi&#39;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="vidstab.VidStab.plot_trajectory">
<code class="sig-name descname">plot_trajectory</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.VidStab.plot_trajectory" title="Permalink to this definition">¶</a></dt>
<dd><p>Plot video trajectory</p>
<p>Create a plot of the video’s trajectory &amp; smoothed trajectory.
Separate subplots are used to show the x and y trajectory.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p>tuple of matplotlib objects <code class="docutils literal notranslate"><span class="pre">(Figure,</span> <span class="pre">(AxesSubplot,</span> <span class="pre">AxesSubplot))</span></code></p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab</span> <span class="kn">import</span> <span class="n">VidStab</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="k">as</span> <span class="nn">plt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">gen_transforms</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">plot_trajectory</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="vidstab.VidStab.plot_transforms">
<code class="sig-name descname">plot_transforms</code><span class="sig-paren">(</span><em class="sig-param">radians=False</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.VidStab.plot_transforms" title="Permalink to this definition">¶</a></dt>
<dd><p>Plot stabilizing transforms</p>
<p>Create a plot of the transforms used to stabilize the input video.
Plots x &amp; y transforms (dx &amp; dy) in a separate subplot than angle transforms (da).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>radians</strong> – Should angle transforms be plotted in radians?  If <code class="docutils literal notranslate"><span class="pre">false</span></code>, transforms are plotted in degrees.</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>tuple of matplotlib objects <code class="docutils literal notranslate"><span class="pre">(Figure,</span> <span class="pre">(AxesSubplot,</span> <span class="pre">AxesSubplot))</span></code></p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab</span> <span class="kn">import</span> <span class="n">VidStab</span>
<span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="k">as</span> <span class="nn">plt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">gen_transforms</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">plot_transforms</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="vidstab.VidStab.stabilize">
<code class="sig-name descname">stabilize</code><span class="sig-paren">(</span><em class="sig-param">input_path</em>, <em class="sig-param">output_path</em>, <em class="sig-param">smoothing_window=30</em>, <em class="sig-param">max_frames=inf</em>, <em class="sig-param">border_type='black'</em>, <em class="sig-param">border_size=0</em>, <em class="sig-param">layer_func=None</em>, <em class="sig-param">playback=False</em>, <em class="sig-param">use_stored_transforms=False</em>, <em class="sig-param">show_progress=True</em>, <em class="sig-param">output_fourcc='MJPG'</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.VidStab.stabilize" title="Permalink to this definition">¶</a></dt>
<dd><p>Read video, perform stabilization, &amp; write stabilized video to file</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>input_path</strong> – Path to input video to stabilize.
Will be read with <code class="docutils literal notranslate"><span class="pre">cv2.VideoCapture</span></code>; see opencv documentation for more info.</p></li>
<li><p><strong>output_path</strong> – Path to save stabilized video.
Will be written with <code class="docutils literal notranslate"><span class="pre">cv2.VideoWriter</span></code>; see opencv documentation for more info.</p></li>
<li><p><strong>smoothing_window</strong> – window size to use when smoothing trajectory</p></li>
<li><p><strong>max_frames</strong> – The maximum amount of frames to stabilize/process.
The list of available codes can be found in fourcc.org.
See cv2.VideoWriter_fourcc documentation for more info.</p></li>
<li><p><strong>border_type</strong> – How to handle negative space created by stabilization translations/rotations.
Options: <code class="docutils literal notranslate"><span class="pre">['black',</span> <span class="pre">'reflect',</span> <span class="pre">'replicate']</span></code></p></li>
<li><p><strong>border_size</strong> – Size of border in output.
Positive values will pad video equally on all sides,
negative values will crop video equally on all sides,
<code class="docutils literal notranslate"><span class="pre">'auto'</span></code> will attempt to minimally pad to avoid cutting off portions of transformed frames</p></li>
<li><p><strong>layer_func</strong> – Function to layer frames in output.
The function should accept 2 parameters: foreground &amp; background.
The current frame of video will be passed as foreground,
the previous frame will be passed as the background
(after the first frame of output the background will be the output of
layer_func on the last iteration)</p></li>
<li><p><strong>use_stored_transforms</strong> – should stored transforms from last stabilization be used instead of
recalculating them?</p></li>
<li><p><strong>playback</strong> – Should the a comparison of input video/output video be played back during process?</p></li>
<li><p><strong>show_progress</strong> – Should a progress bar be displayed to console?</p></li>
<li><p><strong>output_fourcc</strong> – FourCC is a 4-byte code used to specify the video codec.</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>Nothing is returned.  Output of stabilization is written to <code class="docutils literal notranslate"><span class="pre">output_path</span></code>.</p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab.VidStab</span> <span class="kn">import</span> <span class="n">VidStab</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">stabilize</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">,</span> <span class="n">output_path</span><span class="o">=</span><span class="s1">&#39;stable_video.avi&#39;</span><span class="p">)</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">(</span><span class="n">kp_method</span> <span class="o">=</span> <span class="s1">&#39;ORB&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">stabilize</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">,</span> <span class="n">output_path</span><span class="o">=</span><span class="s1">&#39;stable_video.avi&#39;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="method">
<dt id="vidstab.VidStab.stabilize_frame">
<code class="sig-name descname">stabilize_frame</code><span class="sig-paren">(</span><em class="sig-param">input_frame</em>, <em class="sig-param">smoothing_window=30</em>, <em class="sig-param">border_type='black'</em>, <em class="sig-param">border_size=0</em>, <em class="sig-param">layer_func=None</em>, <em class="sig-param">use_stored_transforms=False</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.VidStab.stabilize_frame" title="Permalink to this definition">¶</a></dt>
<dd><p>Stabilize single frame of video being iterated</p>
<p>Perform video stabilization a single frame at a time.  Outputted stabilized frame will be on a
<code class="docutils literal notranslate"><span class="pre">smoothing_window</span></code> delay.  When frames processed is <code class="docutils literal notranslate"><span class="pre">&lt;</span> <span class="pre">smoothing_window</span></code>, black frames will be returned.
When frames processed is <code class="docutils literal notranslate"><span class="pre">&gt;=</span> <span class="pre">smoothing_window</span></code>, the stabilized frame <code class="docutils literal notranslate"><span class="pre">smoothing_window</span></code> ago will be
returned.  When <code class="docutils literal notranslate"><span class="pre">input_frame</span> <span class="pre">is</span> <span class="pre">None</span></code> stabilization will still be attempted, if there are not frames left to
process then <code class="docutils literal notranslate"><span class="pre">None</span></code> will be returned.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>input_frame</strong> – An OpenCV image (as numpy array) or None</p></li>
<li><p><strong>smoothing_window</strong> – window size to use when smoothing trajectory</p></li>
<li><p><strong>border_type</strong> – How to handle negative space created by stabilization translations/rotations.
Options: <code class="docutils literal notranslate"><span class="pre">['black',</span> <span class="pre">'reflect',</span> <span class="pre">'replicate']</span></code></p></li>
<li><p><strong>border_size</strong> – Size of border in output.
Positive values will pad video equally on all sides,
negative values will crop video equally on all sides,
<code class="docutils literal notranslate"><span class="pre">'auto'</span></code> will attempt to minimally pad to avoid cutting off portions of transformed frames</p></li>
<li><p><strong>layer_func</strong> – Function to layer frames in output.
The function should accept 2 parameters: foreground &amp; background.
The current frame of video will be passed as foreground,
the previous frame will be passed as the background
(after the first frame of output the background will be the output of
layer_func on the last iteration)</p></li>
<li><p><strong>use_stored_transforms</strong> – should stored transforms from last stabilization be used instead of
recalculating them?</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p>1 of 3 outputs will be returned:</p>
<ul class="simple">
<li><dl class="simple">
<dt>Case 1 - Stabilization process is still warming up</dt><dd><ul>
<li><p><strong>An all black frame of same shape as input_frame is returned.</strong></p></li>
<li><p>A minimum of <code class="docutils literal notranslate"><span class="pre">smoothing_window</span></code> frames need to be processed to perform stabilization.</p></li>
<li><p>This behavior was based on <code class="docutils literal notranslate"><span class="pre">cv2.bgsegm.createBackgroundSubtractorMOG()</span></code>.</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Case 2 - Stabilization process is warmed up and <code class="docutils literal notranslate"><span class="pre">input_frame</span> <span class="pre">is</span> <span class="pre">not</span> <span class="pre">None</span></code></dt><dd><ul>
<li><p><strong>A stabilized frame is returned</strong></p></li>
<li><p>This will not be the stabilized version of <code class="docutils literal notranslate"><span class="pre">input_frame</span></code>.
Stabilization is on an <code class="docutils literal notranslate"><span class="pre">smoothing_window</span></code> frame delay</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Case 3 - Stabilization process is finished</dt><dd><ul>
<li><p><strong>None</strong></p></li>
</ul>
</dd>
</dl>
</li>
</ul>
</p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab.VidStab</span> <span class="kn">import</span> <span class="n">VidStab</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">vidcap</span> <span class="o">=</span> <span class="n">cv2</span><span class="o">.</span><span class="n">VideoCapture</span><span class="p">(</span><span class="s1">&#39;input_video.mov&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">grabbed_frame</span><span class="p">,</span> <span class="n">frame</span> <span class="o">=</span> <span class="n">vidcap</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># Pass frame to stabilizer even if frame is None</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="c1"># stabilized_frame will be an all black frame until iteration 30</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="n">stabilized_frame</span> <span class="o">=</span> <span class="n">stabilizer</span><span class="o">.</span><span class="n">stabilize_frame</span><span class="p">(</span><span class="n">input_frame</span><span class="o">=</span><span class="n">frame</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>                                                  <span class="n">smoothing_window</span><span class="o">=</span><span class="mi">30</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span>    <span class="k">if</span> <span class="n">stabilized_frame</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="c1"># There are no more frames available to stabilize</span>
<span class="gp">&gt;&gt;&gt; </span>        <span class="k">break</span>
</pre></div>
</div>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="utility-functions">
<h2>Utility functions<a class="headerlink" href="#utility-functions" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="vidstab.download_ostrich_video">
<code class="sig-prename descclassname">vidstab.</code><code class="sig-name descname">download_ostrich_video</code><span class="sig-paren">(</span><em class="sig-param">download_to_path</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.download_ostrich_video" title="Permalink to this definition">¶</a></dt>
<dd><p>Download example shaky clip of ostrich used in README (mp4)</p>
<p>Video used with permission the HappyLiving YouTube channel.
Original video: <a class="reference external" href="https://www.youtube.com/watch?v=9pypPqbV_GM">https://www.youtube.com/watch?v=9pypPqbV_GM</a></p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>download_to_path</strong> – path to save video to</p>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>None</p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab</span> <span class="kn">import</span> <span class="n">VidStab</span><span class="p">,</span> <span class="n">download_ostrich_video</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">path</span> <span class="o">=</span> <span class="s1">&#39;ostrich.mp4&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">download_ostrich_video</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">stabilize</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s1">&#39;output_path.avi&#39;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="vidstab.layer_blend">
<code class="sig-prename descclassname">vidstab.</code><code class="sig-name descname">layer_blend</code><span class="sig-paren">(</span><em class="sig-param">foreground</em>, <em class="sig-param">background</em>, <em class="sig-param">foreground_alpha=0.6</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.layer_blend" title="Permalink to this definition">¶</a></dt>
<dd><p>blend a foreground image over background (wrapper for cv2.addWeighted)</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>foreground</strong> – image to be laid over top of background image</p></li>
<li><p><strong>background</strong> – image to over laid with foreground image</p></li>
<li><p><strong>foreground_alpha</strong> – alpha to apply to foreground; (1 - foreground_alpha) applied to background</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>return combined image where foreground is laid over background with alpha</p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab</span> <span class="kn">import</span> <span class="n">VidStab</span><span class="p">,</span> <span class="n">layer_overlay</span><span class="p">,</span> <span class="n">layer_blend</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">stabilize</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;my_shaky_video.avi&#39;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>                     <span class="n">output_path</span><span class="o">=</span><span class="s1">&#39;stabilized_output.avi&#39;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>                     <span class="n">border_size</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>                     <span class="n">layer_func</span><span class="o">=</span><span class="n">layer_blend</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="function">
<dt id="vidstab.layer_overlay">
<code class="sig-prename descclassname">vidstab.</code><code class="sig-name descname">layer_overlay</code><span class="sig-paren">(</span><em class="sig-param">foreground</em>, <em class="sig-param">background</em><span class="sig-paren">)</span><a class="headerlink" href="#vidstab.layer_overlay" title="Permalink to this definition">¶</a></dt>
<dd><p>put an image over the top of another</p>
<p>Intended for use in VidStab class to create a trail of previous frames in the stable video output.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>foreground</strong> – image to be laid over top of background image</p></li>
<li><p><strong>background</strong> – image to over laid with foreground image</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>return combined image where foreground is laid over background</p>
</dd>
</dl>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">vidstab</span> <span class="kn">import</span> <span class="n">VidStab</span><span class="p">,</span> <span class="n">layer_overlay</span><span class="p">,</span> <span class="n">layer_blend</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span> <span class="o">=</span> <span class="n">VidStab</span><span class="p">()</span>
<span class="go">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">stabilizer</span><span class="o">.</span><span class="n">stabilize</span><span class="p">(</span><span class="n">input_path</span><span class="o">=</span><span class="s1">&#39;my_shaky_video.avi&#39;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>                     <span class="n">output_path</span><span class="o">=</span><span class="s1">&#39;stabilized_output.avi&#39;</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>                     <span class="n">border_size</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span>
<span class="gp">&gt;&gt;&gt; </span>                     <span class="n">layer_func</span><span class="o">=</span><span class="n">layer_overlay</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

</div>
</div>


           </div>
           
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
      
        <a href="usage.html" class="btn btn-neutral float-left" title="Basic usage" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2018, Adam Spannbauer

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. 

</footer>

        </div>
      </div>

    </section>

  </div>
  


  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script>

  
  
    
   

</body>
</html>